---
title: Separate Server Integration
---

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";

Run Mastra as a standalone server and connect your Next.js frontend (using Assistant UI) to its API endpoints. This approach separates your AI backend from your frontend application, allowing for independent development and scaling.

<Steps>

<Step>

### Create Mastra Server Project

First, create a dedicated project for your Mastra server. Choose a directory separate from your Next.js/Assistant UI frontend project.

Navigate to your chosen parent directory in the terminal and run the Mastra create command:

```bash
npx create-mastra@latest
```

This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project. For more detailed setup instructions, refer to the [official Mastra installation guide](https://mastra.ai/docs/getting-started/installation).

Once the setup is complete, navigate into your new Mastra project directory (the name you provided during the setup):

```bash
cd your-mastra-server-directory # Replace with the actual directory name
```

You now have a basic Mastra server project ready.

<Callout title="API Keys">
  Ensure you have configured your environment variables (e.g., `OPENAI_API_KEY`)
  within this Mastra server project, typically in a `.env.development` file, as
  required by the models you use. The `create-mastra` wizard might prompt you
  for some keys, but ensure all necessary keys for your chosen models are
  present.
</Callout>

</Step>

<Step>

### Define the Agent

Next, let's define an agent within your Mastra server project. We'll create a `chefAgent` similar to the one used in the full-stack guide.

Open or create the agent file (e.g., `src/agents/chefAgent.ts` within your Mastra project) and add the following code:

```typescript title="src/agents/chefAgent.ts"
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

export const chefAgent = new Agent({
  name: "chef-agent",
  instructions:
    "You are Michel, a practical and experienced home chef. " +
    "You help people cook with whatever ingredients they have available.",
  model: openai("gpt-4o-mini"),
});
```

This defines the agent's behavior, but it's not yet active in the Mastra server.

</Step>

<Step>

### Register the Agent

Now, you need to register the `chefAgent` with your Mastra instance so the server knows about it. Open your main Mastra configuration file (this is often `src/index.ts` in projects created with `create-mastra`).

Import the `chefAgent` and add it to the `agents` object when initializing Mastra:

```typescript title="src/index.ts"
import { Mastra } from "@mastra/core";
import { chefAgent } from "./agents/chefAgent"; // Adjust path if necessary

export const mastra = new Mastra({
  agents: { chefAgent },
});
```

Make sure you adapt this code to fit the existing structure of your `src/index.ts` file generated by `create-mastra`. The key is to import your agent and include it in the `agents` configuration object.

</Step>

<Step>

### Run the Mastra Server

With the agent defined and registered, start the Mastra development server:

```bash npm2yarn
npm run dev
```

By default, the Mastra server will run on `http://localhost:4111`. Your `chefAgent` should now be accessible via a POST request endpoint, typically `http://localhost:4111/api/agents/chefAgent/stream`. Keep this server running for the next steps where we'll set up the Assistant UI frontend to connect to it.

</Step>

<Step>

### Initialize Assistant UI Frontend

Now, set up your frontend application using Assistant UI. Navigate to a **different directory** from your Mastra server project. You can either create a new Next.js project or use an existing one.

Inside your frontend project directory, run one of the following commands:

```sh title="New Project"
npx assistant-ui@latest create
```

```sh title="Existing Project"
npx assistant-ui@latest init
```

This command installs the necessary Assistant UI dependencies and sets up basic configuration files, including a default chat page and an API route (`app/api/chat/route.ts`).

<Callout title="Need Help?">
  For detailed setup instructions for Assistant UI, including manual setup
  steps, please refer to the main [Getting Started
  guide](/docs/getting-started).
</Callout>

In the next step, we will configure this frontend to communicate with the separate Mastra server instead of using the default API route.

</Step>

<Step>

### Configure Frontend API Endpoint

The default Assistant UI setup configures the chat runtime to use a local API route (`/api/chat`) within the Next.js project. Since our Mastra agent is running on a separate server, we need to update the frontend to point to that server's endpoint.

Open the main page file in your Assistant UI frontend project (usually `app/page.tsx` or `src/app/page.tsx`). Find the `useChatRuntime` hook and change the `api` property to the full URL of your Mastra agent's stream endpoint:

```tsx {10} title="app/page.tsx"
"use client";
import { Thread } from "@/components/assistant-ui/thread";
import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { ThreadList } from "@/components/assistant-ui/thread-list";

export default function Home() {
  // Point the runtime to the Mastra server endpoint
  const runtime = useDataStreamRuntime({
    api: "http://localhost:4111/api/agents/chefAgent/stream",
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <main className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
        <ThreadList />
        <Thread />
      </main>
    </AssistantRuntimeProvider>
  );
}
```

Replace `"http://localhost:4111/api/agents/chefAgent/stream"` with the actual URL if your Mastra server runs on a different port or host, or if your agent has a different name.

Now, the Assistant UI frontend will send chat requests directly to your running Mastra server.

<Callout title="Delete Default API Route">
  Since the frontend no longer uses the local `/api/chat` route created by the
  `init` command, you can safely delete the `app/api/chat/route.ts` (or
  `src/app/api/chat/route.ts`) file from your frontend project.
</Callout>

</Step>

<Step>

### Run the Frontend Application

You're ready to connect the pieces! Make sure your separate Mastra server is still running (from Step 4).

In your Assistant UI frontend project directory, start the Next.js development server:

```bash npm2yarn
npm run dev
```

Open your browser to `http://localhost:3000` (or the port specified in your terminal for the frontend app). You should now be able to interact with your `chefAgent` through the Assistant UI chat interface. The frontend will make requests to your Mastra server running on `http://localhost:4111`.

</Step>

</Steps>

Congratulations! You have successfully integrated Mastra with Assistant UI using a separate server approach. Your Assistant UI frontend now communicates with a standalone Mastra agent server.

This setup provides a clear separation between your frontend and AI backend. To explore more advanced Mastra features like memory, tools, workflows, and deployment options, please refer to the [official Mastra documentation](https://mastra.ai/docs).
